home *** CD-ROM | disk | FTP | other *** search
/ Aminet 35 / Aminet 35 (2000)(Schatztruhe)[!][Feb 2000].iso / Aminet / hard / hack / mccontrol.lha / MCControl / Modules / Modules.doc < prev    next >
Encoding:
Text File  |  1999-12-12  |  14.6 KB  |  408 lines
  1. ;----------------------------------------------------------------------------
  2. ;This is not an documentation how to use the .mcm modules in your own
  3. ;software! Its an documentation about how to write modules for other
  4. ;card reader.
  5. ;----------------------------------------------------------------------------
  6. TABLE OF CONTENTS
  7.  
  8. MCControlModule/General
  9. MCControlModule/Module_Delay
  10. MCControlModule/Module_Open
  11. MCControlModule/Module_FrameOpen
  12. MCControlModule/Module_FrameClose
  13. MCControlModule/Module_ReadCommand
  14. MCControlModule/Module_WriteCommand
  15. MCControlModule/Module_PADOpen
  16. MCControlModule/Module_PADClose
  17. MCControlModule/Module_PADCommand
  18. MCControlModule/Module_DirectFrame
  19. MCControlModule/Module_DirectPage
  20. ;----------------------------------------------------------------------------
  21.  *General*
  22.  
  23. First the main structure:
  24.  
  25.         RSRESET
  26. Module_RTS                   rs.w 1 ;to avoid crash when user is starting module
  27. Module_Version               rs.w 1 ;Currently 1
  28. Module_ID                    rs.l 1 ;must be "MCCM"
  29. Module_Flags                 rs.l 1 ;Unused Flags must be ZERO
  30. Module_Exec_Base             rs.l 1 ;Filled by MCControl
  31. Module_Dos_Base              rs.l 1 ;Filled by MCControl
  32. Module_Intuition_Base        rs.l 1 ;Filled by MCControl
  33. ;--- Card Data
  34. Module_DelayReadByte         rs.l 1 ;Filled by MCControl
  35. Module_DelayReadBit          rs.l 1 ;Filled by MCControl
  36. Module_DelayWriteByte        rs.l 1 ;Filled by MCControl
  37. Module_DelayWriteBit         rs.l 1 ;Filled by MCControl
  38.                              rs.l 10 ;reserved (must be ZERO)
  39. ;--- Jump Table
  40. Module_Delay                 rs.w 3 ;Filled by MCControl
  41. Module_Open                  rs.w 3
  42. Module_Close                 rs.w 3
  43. Module_FrameOpen             rs.w 3
  44. Module_FrameClose            rs.w 3
  45. Module_ReadCommand           rs.w 3
  46. Module_WriteCommand          rs.w 3
  47. Module_PADOpen               rs.w 3
  48. Module_PADClose              rs.w 3
  49. Module_PADCommand            rs.w 3
  50. Module_DirectFrame           rs.w 3
  51. Module_DirectPage            rs.w 3
  52.                              rs.w 3*8 ;reserved
  53. Module_SIZEOF                rs.b 0
  54. ;----------------------------------------------------------------------------
  55.  BITDEF Module,Delay,0         ;Tell MCControl you require timing data.
  56.  BITDEF Module,Device,1        ;Tell MCControl you require an Device/Unit
  57.                                ;selector
  58.  BITDEF Module,MultiPage,2     ;Tell MCControl you support MultiPage cards
  59.  BITDEF Module,DirectAccess,3  ;Tell MCControl you support DirectAccess support
  60. ;----------------------------------------------------------------------------
  61. Module_Error_NoError       = 0
  62. Module_Error_OpenDevice    = 1
  63. Module_Error_NotCompatible = 2 ;If hardware supports identification!
  64. Module_Error_NoTimerDevice = 3 ;If you need the timer.device and opening fails
  65. Module_Error_OutOfMemory   = 20
  66. ;----------------------------------------------------------------------------
  67. Module_DirectFrame_Read    = 0
  68. Module_DirectFrame_Write   = 1
  69. ;----------------------------------------------------------------------------
  70. Module_DirectPage_Next     = 0
  71. Module_DirectPage_Prev     = 1
  72. ;----------------------------------------------------------------------------
  73.  
  74.  NOTES 
  75.  
  76.    The exec, dos and intuition bases are free. Just use them.  This  saves
  77.    memory,  time and of cource code size. The card data is for free usage,
  78.    too.
  79.  
  80.    Beside the arguments delivered for  each  function  you´ll  receive  an
  81.    pointer on the module itself in register A4!
  82.  
  83.    Make sure to backup a2-a5 and d2-d7 just like the Amiga-OS is doing!
  84.  
  85.    You must implement port and device allocation into Module_Open()! Don´t
  86.    try  to  play  with  the hardware without owning the right to do so. If
  87.    possible try to use parallel.device or serial.device. (The user defined
  88.    device will be given during Module_Open().
  89.        
  90.    Its not required to create an real jumptable, by using JMPs. Feel free,
  91.    to use an BRA followed by an NOP. (See RamCard.mcm)
  92.        
  93.    Its strongly  required  to  implement  all  given  jumps.  (except  the
  94.    Module_Delay).
  95.  
  96.    Implement the code as fast as possible, because its used for many times
  97.    during reading and writing memory cards. Try to avoid overhead by using
  98.    Module_Open, or if not possible Module_FrameOpen.
  99.  
  100.    Feel free to use the Module_Delay function even  if  the  ModuleF_Delay
  101.    flags  isn´t  set!  The  flag  only  deactivates the gadgets and avoids
  102.    filling out the timing sheet (Module_Delayyyyxxxx)!
  103.        
  104.    Your reader expects only a frame number and returns a  complete  frame?
  105.    Well,  this  isn´t  a problem. Set the Module_Flag ModuleF_DirectAccess
  106.    and MCControl is using Module_DirectFrame insteed of  Module_FrameOpen,
  107.    Module_FrameClose,    Module_ReadCommand    and    Module_WriteCommand!
  108.    Module_DirectFrame is doing the same job for reading and writing.  Just
  109.    take a look on my RamCard.mcm as an DirectFrame Example.
  110.  
  111.    If you need help then ask me and I am telling you what to  do.  If  you
  112.    don´t  know how to code a driver then send me your information and I´ll
  113.    do my very best.
  114.  
  115. ;----------------------------------------------------------------------------
  116. MCControlModule/Module_Delay
  117.  
  118.    NAME
  119.                  Module_Delay
  120.         
  121.    SYNOPSIS
  122.                  Module_Delay(Time);
  123.                               D0
  124.  
  125.                  Module_Delay(ULONG);
  126.  
  127.    FUNCTION
  128.                  Standard MCControl timer for high speed delay
  129.                  calculations.
  130.  
  131.    INPUTS
  132.                  Time faktor (use Module_Delay#? field for getting
  133.                  values. The delay is on all systems nearly identicaly.
  134.    WARNING
  135.                  Due multi tasking it is possible that this delay is
  136.                  much longer, but this should be no problem.
  137. ;----------------------------------------------------------------------------
  138. MCControlModule/Module_Open
  139.  
  140.    NAME
  141.                  Module_Open -- open and inits the module
  142.  
  143.    SYNOPSIS
  144.                  Error   = Module_Open(Device, Unit)
  145.                  D0                    a0,     d0
  146.  
  147.                  (ULONG) = Module_Open(*UBYTE,ULONG)
  148.    FUNCTION
  149.                  Open the required device and alloc additional memory
  150.                  if needed.
  151.    INPUTS
  152.                  Device: Pointer on device name (STRING IS READ ONLY!!!)
  153.                  Unit:   Unit of the given device
  154.    RESULT
  155.                   0 = No Error
  156.                   1 = Open device error
  157.                   2 = Not compatible
  158.                  20 = Out of memory
  159.  
  160.                  Other results are currently not allowed!!
  161.    NOTES
  162.                  Device and Unit are only valid if the Device-Flag within
  163.                  the module structure (Module_Flags) is set.
  164.  
  165.    SEE ALSO
  166.                  Module_Close()
  167. ;----------------------------------------------------------------------------
  168. MCControlModule/Module_Close
  169.  
  170.    NAME
  171.                  Module_Close -- free all data and close all devices.
  172.  
  173.    SYNOPSIS
  174.                  Module_Close()
  175.  
  176.    FUNCTION
  177.                  Close all devices and free all allocated memory .
  178.    NOTES
  179.                  Module_Close must be save to be called more than
  180.                  one time. This means you must detect an closing of
  181.                  an just closed module. In this case you must return
  182.                  without any action.
  183.    SEE ALSO
  184.                  Module_Open()
  185. ;----------------------------------------------------------------------------
  186. MCControlModule/Module_FrameOpen
  187.  
  188.    NAME
  189.                  Module_FrameOpen -- Prepare for frame read/write
  190.  
  191.    SYNOPSIS
  192.                  Error   = Module_FrameOpen(Slot)
  193.                  D0                          D0
  194.  
  195.                  (ULONG) = Module_FrameOpen(UWORD);
  196.  
  197.    INPUTS
  198.                  Slot: (0-x) Number of slot to access!
  199.  
  200.    RESULT
  201.                   0 = No Error
  202.                   1 = Slot not available
  203.                  -1 = Other Error (you shouldn´t need to use this)
  204.  
  205.                  Other results are currently not allowed!!
  206.  
  207.    FUNCTION
  208.                  No special function. Just do what is required to
  209.                  access the given slot. Standard.mcm is using this
  210.                  function to active the select line of the given
  211.                  slot. RamCard.mcm is resetting data buffers only.
  212.    SEE ALSO
  213.                  Module_FrameClose()
  214. ;----------------------------------------------------------------------------
  215. MCControlModule/Module_FrameClose
  216.  
  217.    NAME
  218.                  Module_FrameClose -- frame read/write done
  219.  
  220.    SYNOPSIS
  221.                  Module_FrameClose()
  222.  
  223.    FUNCTION
  224.                  No special function. Just do what is required after
  225.                  reading a frame. Standard.mcm is using this
  226.                  function to deactive all select lines slot.
  227.    SEE ALSO
  228.                  Module_FrameOpen()
  229. ;----------------------------------------------------------------------------
  230. MCControlModule/Module_ReadCommand
  231.  
  232.    NAME
  233.                  Module_ReadCommand -- Send command and get answer
  234.  
  235.    SYNOPSIS
  236.                  Result = Module_ReadCommand(Command)
  237.                  D0                          D0
  238.  
  239.                  BYTE   = Module_ReadCommand(BYTE)
  240.  
  241.    FUNCTION
  242.                  Command will be transfered to memory card. The
  243.                  card answer will be returned to Result.
  244.  
  245.    NOTES
  246.                  There is no need to implement different routines
  247.                  for Module_ReadCommand and Module_WriteCommand.
  248.                  Internaly these commands are working equal. The
  249.                  only difference is that the ReadCommand is used
  250.                  when reading frames and the WriteCommand on writing
  251.                  frames. This allows to use different delays for
  252.                  reading and writing. If you hardware isn´t using
  253.                  any different delays use the same routine
  254.                  for both commands.
  255.  
  256.    SEE ALSO
  257.                  Module_WriteCommand()
  258. ;----------------------------------------------------------------------------
  259. MCControlModule/Module_WriteCommand
  260.  
  261.    NAME
  262.                  Module_WriteCommand -- Send command and get answer
  263.  
  264.    SYNOPSIS
  265.                  Result = Module_WriteCommand(Command)
  266.                  D0                           D0
  267.  
  268.                  BYTE = Module_WriteCommand(BYTE)
  269.  
  270.    FUNCTION
  271.                  Command will be transfered to memory card. The
  272.                  card answer will be returned to Result.
  273.  
  274.    NOTES
  275.                  There is no need to implement different routines
  276.                  for Module_ReadCommand and Module_WriteCommand.
  277.                  Internaly these commands are working equal. The
  278.                  only difference is that the ReadCommand is used
  279.                  when reading frames and the WriteCommand on writing
  280.                  frames. This allows to use different delays for
  281.                  reading and writing. If you hardware isn´t using
  282.                  any different delays use the same routine
  283.                  for both commands.
  284.                        
  285.    SEE ALSO
  286.                  Module_ReadCommand()
  287. ;----------------------------------------------------------------------------
  288. MCControlModule/Module_PADOpen
  289.  
  290.    NAME
  291.                  Module_PADOpen -- Prepare for PAD emulation
  292.  
  293.    SYNOPSIS
  294.                  Error   = Module_PADOpen()
  295.                  d0
  296.  
  297.                  (LONG)  = Module_PADOpen()
  298.  
  299.    RESULT
  300.                  0 = No Error
  301.                  Other results are currently not allowed!!
  302.  
  303.    FUNCTION
  304.                  Again! There is no predefined function for this
  305.                  function. Just do what is required or even nothing.
  306.                  Standard.mcm is using this function to set all
  307.                  IO ports to output.
  308.    SEE ALSO
  309.                  Module_PADClose()
  310. ;----------------------------------------------------------------------------
  311. MCControlModule/Module_PADClose
  312.  
  313.    NAME
  314.                  Module_PADClose -- PAD emulation done
  315.  
  316.    SYNOPSIS
  317.                  Module_PADClose()
  318.  
  319.    FUNCTION
  320.                  Again there is no predefined function for this
  321.                  function. Just do what is required or even nothing.
  322.                  Standard.mcm is using this function to reset all
  323.                  IO ports to default.
  324.    SEE ALSO
  325.                  Module_PADClose()
  326. ;----------------------------------------------------------------------------
  327. MCControlModule/Module_PADCommand
  328.  
  329.    NAME
  330.                  Module_PADCommand -- Simulate PAD
  331.  
  332.    SYNOPSIS
  333.                  Module_PADCommand(Command,Answer)
  334.                                    D0,     D1
  335.  
  336.                  Module_PADCommand(BYTE   ,BYTE)
  337.         
  338.    FUNCTION
  339.                  Well, this is a little tricky. You must send the
  340.                  Command on the command line, while simulating
  341.                  an PSX Pad answer on the Dataline by using Answer.
  342.                         
  343.                  The card will think its hearing the playstation is
  344.                  talking to a card and vice versa.
  345.    SEE ALSO
  346.                  Module_PADOpen(), Module_PADClose()
  347. ;----------------------------------------------------------------------------
  348. MCControlModule/Module_DirectFrame
  349.  
  350.    NAME
  351.                  Module_DirectFrame -- Handle 1 frame at once
  352.  
  353.    SYNOPSIS
  354.                  Error   = Module_DirectFrame(Frame,Mode,Data)
  355.                  D0                           D0,   D1,  A0
  356.  
  357.                  (LONG)  = Module_DirectFrame(WORD, LONG,*Byte)
  358.  
  359.    INPUTS
  360.                  Frame: Frame number to read or write!
  361.                  Mode:  Module_DirectFrame_Read or Module_DirectFrame_Write
  362.                  Data:  Pointer on Buffer!
  363.  
  364.    RESULT
  365.                   0 = Ok
  366.                  -1 = ERROR
  367.  
  368.                  Other results are currently not allowed!!
  369.  
  370.    FUNCTION
  371.                  Read or write the given frame (128 bytes)!
  372.  
  373.    NOTE
  374.                  Data must be 128 bytes long!
  375.                  This function requires the flag: ModuleF_DirectAccess!
  376.                  Otherwise MCControl is ignoring this routine.
  377. ;----------------------------------------------------------------------------
  378. MCControlModule/Module_DirectPage
  379.  
  380.    NAME
  381.                  Module_DirectPage -- Handle page swapping
  382.  
  383.    SYNOPSIS
  384.                  Error   = Module_DirectPage(Offset,Mode)
  385.                  D0                          D0,    D1
  386.  
  387.                  (LONG)  = Module_DirectPage(WORD, LONG)
  388.  
  389.    INPUTS
  390.                  Offset: Number of pages to jump!
  391.                  Mode:   Module_DirectPage_Next or Module_DirectPage_Prev
  392.  
  393.    RESULT
  394.                   0 = Ok
  395.                  -1 = ERROR
  396.  
  397.                  Other results are currently not allowed!!
  398.    FUNCTION
  399.                  Change activ card page of an multipage MemoryCard!
  400.  
  401.    NOTE
  402.                  This function requires the flag: ModuleF_DirectAccess!
  403.                  Otherwise MCControl is ignoring this routine.
  404.  
  405. ;----------------------------------------------------------------------------
  406.  
  407.  
  408.